Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Insetting Shapes

GXInsetShape

You can use the GXInsetShape procedure to inset a shape's geometry.

void GXInsetShape(gxShape target, Fixed inset);

source

A reference to the shape whose geometry you want to inset.

inset

The distance to inset the geometry of the shape.

DESCRIPTION

The GXInsetShape function insets the geometry of the shape specified by the target parameter by the distance specified in the inset parameter. The on-curve geometric points of the resulting geometry are the specified distance inside the contour of the original geometry.

You can specify a positive or negative value for the inset parameter: positive values move the geometry to the inside of the original geometry; negative values move it outside the original geometry.

QuickDraw GX uses the direction of a contour to define which side is the inside of a contour: the inside is the side to the right of the contour. As a result, insetting clockwise contours by a positive amount makes them smaller while insetting counterclockwise contours by a positive amount makes them larger.

You can override this behavior by setting the gxAutoInsetStyle style attribute. If you set this style attribute for a shape, QuickDraw GX finds the true inside of the contour, regardless of its contour direction. With this attribute set, insetting a contour by a positive amount makes it smaller, whether it has a clockwise direction or a counterclockwise direction.

If the target shape has the noFill shape fill, this function posts the error shape_fill_not_allowed.

For empty, full, and point shapes, this function posts the error graphic_type_cannot_be_inset. Line shapes and rectangle shapes are converted to polygon shapes; curve shapes are converted to path shapes.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the error graphic_type_cannot_be_inset
picture	Posts the error graphic_type_cannot_be_inset
text	Posts the error graphic_type_cannot_be_inset
glyph	Posts the error graphic_type_cannot_be_inset
layout	Posts the error graphic_type_cannot_be_inset

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
graphic_type_cannot_be_inset	(debugging version)
shape_fill_not_allowed	(debugging version)
shape_access_not_allowed	(debugging version)
Warnings
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
Notices (debugging version)
geometry_unaffected	(debugging version)

SEE ALSO

For examples using this function, see "Insetting Shapes" beginning on page 4-50.

For a discussion of contours and contour direction, see Chapter 2, "Geometric Shapes," in this book.

For a discussion of the gxAutoInsetStyle style attribute, see Chapter 3, "Geometric Styles," in this book.

To change the bounding rectangle of a shape, use the GXSetShapeBounds function, described on page 4-92.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help